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Broadcasting with 
QuickTime 5 



QuickTime 5 introduces new broadcasting APIs that allow third-party 
developers to write broadcasting applications, or to add broadcasting to their 
existing applications. This document discusses some of the features, 
capabilities, and usage of these broadcasting APIs. 

Note that these APIs have not been finalized as of this writing, so the 
information here is by definition preliminary and subject to change. 

If you are interested in participating in a QuickTime seeding program and 
providing feedback on the new APIs, please send email to 

qtswfeedback@apple.com. 

Your feedback is welcome and encouraged. 


Broadcasting APIs 


The new QuickTime broadcasting APIs are designed to allow you to create 
standards-compliant RTP broadcasts. This means that non-QuickTime clients 
can play back your broadcasts. The new APIs comprise part of the 
QTSPresentati on API related to broadcasting and the QTSSourcer component 


API. 


(Note that these new broadcasting APIs currently work only on the Mac OS and 
on Mac OS X.) 

Basic broadcasting support of the following is included in the QuickTime 5 
release: 

■ Audio and video streams from the Sequence Grabber. 

■ Stored movies, i.e., audio and video. 

■ Text and URLs. 
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■ Configuration settings with dialogs and info selectors. 

■ The ability to broadcast for extended periods of time without restarting. 

■ Reporting of basic statistics, e.g., number of connected users or network stats. 

■ The ability to broadcast data from different sources (sourcer components). 
The QuickTime-supplied sourcers in this release include: 

■ Sequence Grabber (audio and video only). 

■ Precompressed media, i.e., sourcer that takes a sample description and 
sample data. 

■ Stored movies. 

Broadcasting with these new APIs is straightforward enough. The process 
works as follows: 

When you're broadcasting, QuickTime uses the Sequence Grabber to source the 
media as the default. If you want to generate your own data, your application 
can create a sample description, with a piece of data, and an accompanying 
timestamp. Then you call the new broadcast APIs and the data will be 
broadcast. 


Overview 

QuickTime streaming is structured so that, at the top level, you have what is 
defined as a Presentation, which is analogous to a QuickTime movie. Within a 
Presentation, there are a series of streams, which are similar to the tracks in a 
movie. Streams can be audio, video, or text data. 

QuickTime provides a number of API calls for adding and inspecting stream 
properties, for getting and setting those stream properties, in addition to 
Presentation properties. This is the same for both sending and receiving 
streams. When QuickTime receives a stream, it creates a Presentation, waits for 
data, and then creates a stream with that data. When QuickTime sends a stream, 
it creates the stream and has other components within the stream that generate 
the data and break it into packets. 

In its current implementation, you begin by constructing a stream for 
broadcasting from an SDP (Session Description Protocol) file — SDP is an 
industry standard for RTP streaming. (Later implementations of broadcasting 
may follow a different procedure.) The SDP file specifies a series of streams, i.e., 
whether they are audio or video, and what compressors will be used for them. 
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If you open an SDP file with QTSNewPresentati on, it creates the Presentation 
with the number of streams specified in that file. 

References 

For more information on SDP, refer to http://ietf.org/rfc/rfc2327.txt. 

For information on packing types, refer to http://ietf.org/rfc/rfcl890.txt. 

How RTP works is explained in RFC 1889 available at http://ietf.org/rfc/ 
rf cl889. txt. 

RTSP is explained in RFC 2326 available at http://ietf.org/rfc/rfc2326.txt. 


Creating a Broadcast From a Live Source 


This section describes how you can create a broadcast from a live source, 
specifying which QuickTime APIs to call in order to start the broadcast. (Note 
again that the information in this section is preliminary and subject to change. If 
you are interested in participating in a QuickTime seeding program for 
broadcasting, please send email to qtswfeedback@appl e. com.) 

The example begins with the most common case, and then discusses other 
sourcer types. 

To create a broadcast from a live source, you begin by specifying the 
networking parameters that you want to use. You accomplish this is by using an 
SDP file or SDP data in memory. 

For example: 

c=IN IP4 224.2.1.2/15/1 
m=audio 1000 RTP/AVP 12 
m=video 2000 RTP/AVP 101 
a=rtpmap:101 H263-1998 

In this example, all you need to specify are the c= and m= lines. 

The c= line defines the destination address, in this case multicast with TTL=15; 
the m= lines define the ports to use (port 1000 for audio, 2000 for video in this 
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case). RTP/AVP defines that RTP should be used. The a=rtpmap line defines the 
numbers to be used for dynamic payload types. 

If these are not assigned, they will be allocated, starting from 96 when a 
dynamic packetizer is chosen, and you will need to re-export the sdp file to give 
to the viewers. 

To create a broadcast, fill out QTSPresParams like this: 


struct QTSPresParams { 
UInt32 

QTSEdit ListHandle 
SInt32 
TimeScale 

QTSMediaParams * 
QTSNotificationUPP 
void * 


version; 
edi t Li st; 
flags; 

timeScale; /* set to 0 for default 
timescale */ 

mediaParams; 
notificationProc; 
notificationRefCon; 


typedef struct QTSPresParams QTSPresParams; 

QTSPresParams presParams; 

QTSMediaParams mediaParams; 

QTSPresentation presentation = kQTSInvalidPresentation; 

memseti&presParams , 0, sizeof(presParams)); 

QTSIni ti al i zeMedi a Pa rams (limed i aParams); 

mediaParams.v.width = (Fixed)(myWidth<<16); 
mediaParams.v.height = (Fixed)(myHeight<<16); 
medi aPa rams . v . gWorl d = myGWorld; 
mediaParams.v.gdHandle = myGD; 

if (sNotificationUPP == NULL) { 
sNotificationUPP = 

(QTSNotificationUPP)NewQTSNotificationUPP(_MyNotificationProc); 

) 


presParams.version = kQTSPresParamsVersionl; 

presParams.flags = kQTSAutoModeFlag | kQTSDontShowStatusFIag | 

kQTSSendMedia FIag; presParams.timeScale = kDefaultPresTimeScale; 
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presParams.mediaParams = &mediaParams; 
presParams.notificationProc = sNotificationUPP; 
presParams.notificationRefCon = myRefCon; 

To start from an SDP file: 

err = QTSNewPresentationFromFi1e(myFi1eSpec, &presParams, &presentation); 

To start from SDP data in memory: 

err = QTSNewPresentationFromData(kQTSSDPDataType, mySDPDataPtr, 

mySDPDataLength, &presParams, &presentation); 

Once you have a presentation, you should always idle it, using the QTSPres Idl e 
call, since the presentation may be performing network transactions: 

QTSPresIdle (QTSPresentation inPresentation, 

QTSPresIdleParams * ioParams); 

err = QTSPresIdle(myPresentation,ni1); // As is usual with QT, pass 0 or 

// nil for a parameter to get the 
// default behavior. 

If you want to see what the Sequence Grabber is capturing, call QTSPresPreview 
before starting the broadcast: 

QTSPresPreview (QTSPresentation inPresentation, 

QTSStream inStream, 

const TimeValue64 * inTimeValue, 

Fixed inRate, 

SIn132 i nFI ags ); 

err = QTSPresPreview (myPresentation,kQTSAl1 Streams,ni1,kFixedl,0); 

To configure the capture source, compression, and packetizer use, call 

QTSPresSettingsDialog: 

QTSPresSettingsDialog (QTSPresentation inPresentation, QTSStream 

inStream, SInt32 inFlags, QTSModalFi1terUPP 
inFi1terProc, void * inFi1terProcRefNum); 
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The filter proc is for your application to be called back to service idle events and 
update events. 

The Panel filter proc allows you to accept or reject the display of particular 
settings. Note that settings often interact. If you filter out packetizer settings, 
but leave compression settings in, the packetizer might change anyway. 

If you filter out everything but one panel, it will present that alone. 

err = QTSPresSettingsDialog (myPresentation, kQTSAl1 Streams, 

0 , ni1 .nil .nil .nil); 


If you supply aQTSPanelFilterProc, you'll be called for each panel with a 
QTSPanel Ft 1 terPa rams structure and your refcon. Return true to retain the panel, 
or false to omit it. 


struct QTSPanelFi1terParams { 
SInt32 
QTSStream 
OSType 
OSType 
QTAtomSpec 


version; 
inStream; 
inPanelType; 
inPanelSubType; 
detai1s; 


typedef struct QTSPanelFi1terParams QTPanelFi1terParams; 
/* return true to keep this panel*/ 

typedef CALLBACK_API( Boolean , QTSPanelFi1terProcPtr 
)(QTSPanelFi1terParams *inParams, void *inRefCon); 


Once you are ready to begin a broadcast, callQTSPresPreroll. 

QTSPresPrerol1 (QTSPresentation inPresentation, 

QTSStream inStream, 

UInt32 inTimeValue, 

Fixed in Rate, 

SInt32 inFIags); 

err = QTSPresPrerol1(myPresentation,kQTSAl1 Streams,0,k Fixedl,0); 

You should then call QTSPresIdle until you get a PrerollAck notification via 
your Notification proc. This allows you to cope with server handshaking, if 
necessary, for configuration. 
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err = QTSPresIdle(myPresentation,ni1); 

Once you get the Ack and no error, call QTSPresStart: 

QTSPresStart (QTSPresentation inPresentation, 

QTSStream inStream, 

SIn132 i nFI ags ); 

err = QTSPresStarttmyPresentation,kQTSAl1 Streams,0); 

You keep calling idle until the presentation is over; then you call QTSPresStop. 
When you are finished, dispose the presentation with this call: 

QTSDisposePresentation (QTSPresentation inPresentation, 

SI n132 i nFI ags ); 

For someone to be able to see your broadcast, they need to get a copy of your 
SDP file and open it in QuickTime Player or another RTP-capable application. 

If you want textual summaries of the broadcast settings to display in your 
application, you can call QTSPresGetSetti ngsAsText: 

QTSPresGetSettingsAsText (QTSPresentation inPresentation, 

QTSStream inStream, 

SInt32 inFlags, 

OSType inTextType, 

Handle * outText, 

QTSDi al ogPanel Fi 1 terLIPP inPanelFilterProc, 
void * inPanelFi1terProcRefNum); 

Handle myText=ni1; 

err = QTSPresGetSettingsAsText (myPresentation, kQTSAl1 Streams,0, 

kQTSSettingsTextSummary,&myText, nil, nil); 

The panel filter procs can be used to get settings for a subset of the panels, as 
with the Settings dialog above. 
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Using Data From Different Sources 

If you want to use data from a source other than the Sequence Grabber, you 
need to specify a Sourcer. You can do this by using another sdp extension. After 
each m= line, add a line like this: 

a=x-sourcer:trak 

a=x-sourcer:push 

a=x-sourcer:none 

With the types from this enum 

enum { 

kQTSSGChannelSourcerType = F0UR_CHAR_C0DE('sgch'), 
kQTSMovieTrackSourcerType = F0UR_CHAR_C0DE('trak'), 
kQTSPushDataSourcerType = F0UR_CHAR_C0DE('push') 

1 : 


Alternatively, you can specify 'none' above, and add sourcers later by opening a 
source component instance and using calls like this: 

QTSPresAddSourcer (QTSPresentation inPresentation, 

QTSStream inStream, 

Componentlnstance inSourcer, 

SInt32 inFIags); 

QTSPresRemoveSourcer (QTSPresentation inPresentation, 

QTSStream inStream, 

Componentlnstance inSourcer, 

SInt32 |nFIags); 

QTSPresGetNumSourcers (QTSPresentation inPresentation, 

QTSStream inStream); 

QTSPresGetlndSourcer (QTSPresentation inPresentation, 

QTSStream inStream, 

UInt32 inindex, 

Componentlnstance * outSourcer); 
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Track Sourcer 

The Track Sourcer will send data from a track in a QuickTime movie. You need 
to configure the sourcer by setting the QTSTrackParams with a Setlnfo 
kQTSI nf o_Track, and looping parameters with a. 

You can get the current state back in QTSSourcerTimi ng Pa rams with 
kQTSInfo_SourcerT1 mlng Getlnfo. 


PushData Sourcer 

The PushData Sourcer allows you to send out arbitrary data. You provide a 
sample description and data pointer, and optionally a timestamp. If you don't 
provide a timestamp, the current time will be used. 

enum { 

kQTSPushDataParamsVersionl = 1 

}; 


enum { 

kQTSPushDataFlag_SampleTimelsValid = 0x00000001, 
kQTSPushDataFlag_DurationIsValid = 0x00000002 

); 


struct QTSPushDataParams { 

SInt32 

SInt32 

SampleDescription Handle 

UInt32 
TimeValue64 

TimeValue64 

UInt32 
void * 

}; 

typedef struct QTSPushDataParams 


version; 
f 1 ags; 

sampleDescription; /* caller owns 

the handle */ 

sampleDescSeed; 

sampleTime; /* also set flag if you 
set this */ 

duration; /* also set flag if you 
set this */ 

data Length; 

dataPtr; /* this does not have to be 
a real macintosh Ptr */ 

QTSPushDataParams; 
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Info Selectors 


/* info selectors for sourcers - get and set */ 

kQTSInfo_Track = F0UR_CHAR_C0DE('trak'), /* QTSTrackParams* */ 
kQTSInfo_Loop = F0UR_CHAR_C0DE('1oop'), /* QTSLoopParams* */ 
kQTSInfo_SourcerTiming = F0UR_CHAR_C0DE('stim'), /* 

QTSSourcerTimingParams* */ 

the above 3 are for the Track sourcer 

kQTSInfo_TargetFrameRate = F0UR_CHAR_C0DE('tfps'), /* 

Fixed * in frames per second */ 

This defines the target frame rate from the Sg Sourcer. 

kQTSInfo_PushData = F0UR_CHAR_C0DE('push'). /* QTSPushDataParams* */ 

This lets you send data into a pushdata. 

kQTSInfo_SourcerCal1backProc = F0UR_CHAR_C0DE(’scbp'), /* 

QTSSourcerCal1backProcParams* */ 

This allows you to get called back by a track sourcer when it is completed. 

Spatial Parameters 

Overall, the Presentation has Media Parameters, which define how it is locally 
displayed. In the absence of any other information, what is passed in for 
QTSNewPresentati on will initialize Sourcer values as well. 

The values here can be retrieved with QTSPresGetxxx. For example: 

QTSPresGetMatrix(pres, kQTSAlIStreams.&outMatrix); 

QTSPresGetDimens ions(pres, kQTSAlIStreams.&outWidth.&outHeight); 

If you don't pass kQTSAl 1 Streams, this will go down to the Sourcers for that 
stream instead. 

In addition, for Sequence Grabber sources, there are further selectors for 
cropping, which currently call through to the Sequence Grabber: 

■ kQTSInfo_FullInputRectisa get-only call to find out the maximum rectangle 
of the source. 
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■ kQTSInfo_CroppedInputRect is a get/set call for the cropped rectangle relative 
to the rectangle above. 

Capture settings 


kQTSInfo_InputDeviceName = F0UR_CHAR_C0DE('innm’), /* Handle* */ 
kQTSInfo_InputSourceName = F0UR_CHAR_C0DE('srnm'), /* Handle* */ 

The following calls map through to the VDIG settings: 

kQTSInfo_VideoHue = F0UR_CHAR_C0DE(’hue ’), /* UIntl6* */ 

kQTSInfo_VideoSaturation = F0UR_CHAR_C0DE('satr’), /* UIntl6* */ 
kQTSInfo_VideoContrast = F0UR_CHAR_C0DE('trst’), /* UIntl6* */ 
kQTSInfo_VideoBrightness = F0UR_CHAR_C0DE('brit'), /* UIntl6* */ 
kQTSInfo_VideoSharpness = F0UR_CHAR_C0DE('shrp’) /* UInt16* */ 

The following calls map through to Sound Manager calls: 

kQTSInfo_AudioAutoGainOnOff = F0UR_CHAR_C0DE(’age '), /* 

Boolean* - error if unavailable*/ 
kQTSInfo_AudioGain = F0UR_CHAR_C0DE('gain’), /* 

Fixed* kFixedl is unity gain */ 


Compression Settings 


kQTSInfo_TargetFrameRate = F0UR_CHAR_C0DE(’tfps'), /* 

Fixed * in frames per second */ 
kQTSInfo_TargetDataRate = F0UR_CHAR_C0DE('tdrt'), /* 

UIn132 * in bytes per second */ 

The underlying stdCompression selectors have been exposed, so you can find 
and change compression parameters: 

Visual: 

kQTSInfo_SpatialSettings = F0UR_CHAR_C0DE('sptl’), /* 

pointer to SCSpatialSettings struct*/ 
kQTSInfo_TemporalSettings = F0UR_CHAR_C0DE('tprl'), /* 

pointer to SCTemporalSettings struct*/ 
kQTSInfo_DataRateSettings = F0UR_CHAR_C0DE('drat’), /* 
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pointer to SCDataRateSettings struct*/ 
kQTSInfo_CodecFlags = F0UR_CHAR_C0DE('cfl g'), /* 

pointer to CodecFlags*/ 

kQTSInfo_CodecSettings = F0UR_CHAR_C0DE('cdec'), /* 

pointer to Flandle*/ 

kQTSInfo_ForcekeyVal ue = F0UR_CHAR_C0DE('ksim'), /* 

pointer to long*/ 


Audio: 

kQTSInfo_SoundSampleRate = F0UR_CHAR_C0DE('ssrt'), /* 

pointer to UnsignedFixed*/ 

kQTSInfo_SoundSampleSize = F0UR_CHAR_C0DE('ssss'), /* 

pointer to short*/ 

kQTSInfo_SoundChannelCount = F0UR_CHAR_C0DE('sscc'), /* 

pointer to short*/ 

kQTSInfo_SoundCompression = F0UR_CHAR_C0DE('ssct'), /* 

pointer to OSType*/ 

Codec list for both (setting this can be used to constrain the choice of Codecs): 

kQTSInfo_CompressionList = F0UR_CHAR_C0DE('ctyl'), /* 

pointer to OSType Handle*/ 
kQTSInfo_SGChannel = F0UR_CHAR_C0DE('sgch'), /* 

SGChannel* */ 

This will directly give the SGChannel; its use is discouraged in favor of the 
selectors above. 

Get Info Selectors 

/* get and set */ 

enum { 

kQTSSoundLevelMeteringEnabledlnfo = F0UR_CHAR_C0DE('mtrn'), /* 

Boolean* */ 

kQTSSoundLevelMeterlnfo = F0UR_CHAR_C0DE('1evm'), /* 

LevelMeterlnfoPtr */ 

kQTSSourceTracklDInfo = F0UR_CHAR_C0DE('otid'). /* UInt32* */ 
kQTSSourceLayerlnfo = F0UR_CHAR_C0DE('olyr'). /* UIntl6* */ 
kQTSSourceLanguagelnfo = F0UR_CHAR_C0DE('olng'), /* UIn116* */ 
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kQTSSourceTrackFlagsInfo = F0UR_CHAR_C0DE('otfl’), /* SInt32* */ 
kQTSSourceDimensionsInfo = F0UR_CHAR_C0DE('odim’), /* 
QTSDimensionParams* */ 

kQTSSourceVolumesInfo = F0UR_CHAR_C0DE('ovol’), /* 

QTSVolumesParams* */ 

kQTSSourceMatrixlnfo = F0UR_CHAR_C0DE(’omat'), /* 

MatrixRecord* */ 

kQTSSourceClipRectlnfo = F0UR_CHAR_C0DE('oclp’), /* Rect* */ 
kQTSSourceGraphicsModelnfo = F0UR_CHAR_C0DE(’ogrm’), /* 

QTSGraphicsModeParams* */ 

kQTSSourceScalelnfo = F0UR_CHAR_C0DE('oscl’), /* Point* */ 
kQTSSourceBoundingRectlnfo = F0UR_CHAR_C0DE('orct’), /* Rect* */ 
kQTSSourcellserDatalnfo = F0UR_CHAR_C0DE( ’ oudt ’ ), /* UserData */ 
kQTSSourcelnputMapInfo = F0UR_CHAR_C0DE('oimp'), /* 

QTAtomContainer */ 

); 


/* get only */ 
enum { 

QTSStatisticsParams* */ 

kQTSMinStatusDimensionsInfo = F0UR_CHAR_C0DE('mstd'), /* 
QTSDimensionParams* */ 

kQTSNormalStatusDimensionsInfo = F0UR_CHAR_C0DE('nstd’), /* 
QTSDimensionParams* */ 

kQTSTotalDataRatelnfo = F0UR_CHAR_C0DE('drtt’), /* 

UInt32*, add to what’s there */ 

kQTSTotalDataRatelnlnfo = F0UR_CHAR_C0DE(’drti'), /* 

UInt32*, add to what’s there */ 

kQTSTotalDataRateOutlnfo = F0UR_CHAR_C0DE('drto'), /* 

UInt32*, add to what’s there */ 

kQTSLost Percent Info = F0UR_CHAR_C0DE('1 pet’), /* 

QTSLostPercentParams*, add to what’s there */ 
kQTSNumViewers Info = F0UR_CHAR_C0DE(’nviw'), /* UInt32* */ 
kQTSMediaTypelnfo = F0UR_CHAR_C0DE(’mtyp’), /* OSType* */ 
kQTSNamelnfo = F0UR_CHAR_C0DE(’name’), /* QTSNameParams* */ 
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New Broadcasting APIs 


The following is a preliminary list — from Qui ckTi meStreami ng. h and 
QTStreami ngComponents. h — of some of the broadcasting APIs that are new in 
QuickTime 5.0.1: 

QTSInitializeMediaParams 

QTSNewPresentationFromData 

QTSNewPresentationFromDataRef 

QTSNewPresentationFromFf1e 

QTSNewSourcer 

QTSPresAddSourcer 

QTSPresExport 

QTSPresGetlndSourcer 

QTSPresGetNumSourcers 

QTSPresGetSettingsAsText 

QTSPresPreview 

QTSPres RemoveSourcer 

QTSPresSettingsDi al og 

QTSPresSettingsDial ogWi thFi 1 ters 

QTSSourcerGetEnable 

QTSSourcerGetlnfo 

QTSSourcerGetTimeScale 

QTSSourcerldle 

QTSSourcerlnitial i ze 

QTSSourcerSetEnable 

QTSSourcerSetlnfo 

QTSSourcerSetTimeScale 

The next revision of this document will discuss in detail how these new calls 
work and how you can take advantage of them in writing broadcasting 
applications or adding broadcasting to your existing applications. 
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